﻿#region copyright
//<copyright>
// Copyright(C) 2012 TrackerRealm Corporation
// This file is part of the open source project - Jazz. http://jazz.codeplex.com
// 
// Jazz is open software: you can redistribute it and/or modify it 
// under the terms of the GNU Affero General Public License (AGPL) as published by 
// the Free Software Foundation, version 3 of the License.
// 
// Jazz is distributed in the hope that it will be useful, 
// but WITHOUT ANY WARRANTY; without even the implied warranty 
// of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  
//  See the GNU Affero General Public License (AGPL) for more details.
// 
// You should have received a copy of the GNU General Public 
// License along with Jazz.  If not, see <http://www.gnu.org/licenses/>.
//
// REMOVAL OF THIS NOTICE IS VIOLATION OF THE COPYRIGHT. 
//</copyright>
#endregion
using System;
using System.Collections.Generic;
using System.Text;

namespace TrackerRealm.Jazz.Common
{
    /// <summary>
    /// The status of Jazz objects stored on the server nexus.
    /// <para>Jazz objects in this context are objects with a Guid such as Workflows, 
    ///  Code Classes(jClass) and ParseUnits.  Currently (Feb 2012) the
    /// server only implements the full state features for data objects (such as workflows), not code objects (such as parse units).</para>
    /// <para>Objects can be Valid, Deleted, ArchiveRequest and/or Disconnected (see table below for allowed combinations)</para>
    /// <para>The other bits are included for future capability.</para>
    /// <para>
    /// The server nexus controls the 'Disconnected' and 'Archived' bits. 
    public enum jLifeCycleType
    {
        // The following bit table (currently) only applies to data objects (see definition above of data objects).
        //a)Valid=1, Deleted = 0, ArchiveRequest = 0,  Disconnected = 0 - **Restore = yes         , *DB Search = yes --Initial state.
        //b)Valid=0, Deleted = 1, ArchiveRequest = 0,  Disconnected = 0 - Restore = conditional , DB Search = no  --Deleted state
        //c)Valid=0, Deleted = 1, ArchiveRequest = 0,  Disconnected = 1 - Restore = no          , DB Search = no  --Disconnected state (from Delete)
        //d)Valid=0, Deleted = 0, ArchiveRequest = 0,  Disconnected = 1 - Restore = no          , DB Search = no  --Disconnected state (no Valid references***)
        //
        //e)Valid=0, Deleted = 0, ArchiveRequest = 1,  Disconnected = 0 - Restore = conditional , DB Search = no  --Archive Request state
        //f)Valid=0, Deleted = 0, ArchiveRequest = 1,  Disconnected = 1 - Restore = no          , DB Search = no  --Disconnected state (from Archive Request)
        //
        // * Indicates that the "Search" command is support for Jetfire data objects only.
        // ** Indicates that data is restored to the client nexus (Restore=yes).
        // *** A parent(s) was deleted or the object was created with no parent(s).
        //
        //     +--------------+
        //     |              |
        //     |        +--->(e:ArchiveRequest)---->(f:Disconnected)
        //     v        |
        //    (a:Valid)-+--->(b:Deleted)----------->(c:Disconnected)
        //     |   ^          |
        //     |   +----------+
        //     +----------------------------------->(d:Disconnected)
        /// <summary>
        /// An object should never be in this state.
        /// This could be caused by corrupted data.
        /// Typically indicates some error occured in the restoration of a field.
        /// </summary>
        Unknown = 0,
        /// <summary>
        /// The nexus object is able to be used by the system.
        /// It should be noted that not indicate the storage status (
        /// see '<seealso cref="TjStorageStatusType"/>').
        /// <para>
        /// This is the initial state for any 'storage unit' object.
        /// When this bit is set the object is available to restored to client nexus.</para>
        /// </summary>
        Valid = 1,
        /// <summary>
        /// The ArchiveRequest bit included to support a future capability.
        /// <para>ArchiveRequest operates in a manner simalar to the "Deleted".
        /// An ArchiveRequest object will only be restored to the client nexus if an explicit request is made using the object's Guid.</para>
        /// <para>When a object is in the 'ArchiveRequest' state, and there are no references to the object, it may be placed in the
        /// '<see cref="Disconnected"/>' state.</para>
        /// <para>Archiving objects is a difficult process.  It requires higher level software to insure all relevant references, including code 
        /// (parse units) are also included in the set of archive objects so that they can be successfully de-archived in the future.  
        /// In addition a set of archive objects requires a label, and probably a description, to aid 
        /// in identification.  
        /// The archive process may demand that only complete workspaces may be archived in order to support de-archiving.
        /// Other archive strategies may only allow for data to be restored into special workflows that can not execute code.
        /// </para>
        /// <para>Any archive process (which includes de-archiving) must be regression tested against versioning.</para>
        /// </summary>
        ArchiveRequest = 2,
        /// <summary>
        /// <para>An object is deleted, but otherwise it is a normal object.  Deleted objects are hidden from the user.</para>
        /// A deleted object will only be restored to the client nexus if an explicit request is made using the object's Guid (typically a reference from another object).
        /// <para>When a object is deleted, and there are no references to the object, it may be placed in the
        /// '<see cref="Disconnected"/>' state.</para>
        /// </summary>
        Deleted = 4,
        /// <summary>
        /// A 'Disconnected' object can not
        /// be used and will not be restored to a client nexus.
        /// This bit is set by server nexus during 'Garbage Collection' activity (see Server.GC() method for details).
        /// <para>Typically a 'Disconnected' object will be removed the server nexus;
        /// however it may need to be archived first.  This depends on the server nexus policy.</para>
        /// <para>Any process to remove objects from the server must take into account the 'ArchiveRequest' bit settings of all
        /// other objects stored in the server nexus should such as policy be implemented.  </para>
        /// </summary>
        Disconnected = 8,
        /// <summary>
        /// Currently not used.
        /// </summary>
        TBD = 16,
        /// <summary>
        /// Currently not used.
        /// Indicates that the storage unit has been stored on secondary storge.
        /// To be archived the 'Disconnected' bit must be set.
        /// <para>When the 'Archived' bit is set the object can be removed from the server should the server have an archive policy.</para>
        /// </summary>
        Archived = 32,
        /// <summary>
        /// Currently not used.
        /// The storage unit is broken and should not be used.
        /// A Broken object when sent to the server will not be stored.
        /// </summary>
        Broken = 64,
        /// <summary>
        /// Currently not used.
        /// <para>Currently not used.  May be redundant with 'Broken'.</para>
        /// The storage unit is corrupted and will not be stored.
        /// </summary>
        Corrupted = 128,

    }
}